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Although the interface to ODBC is through function calls, database access is specified using SQL 
statements passed as strings to ODBC functions. 


The following fundamental objects are used for every ODBC program. Each object is referenced by a 
handle. 


e Environment Every ODBC application must allocate exactly one environment using 
SQLAIlocEnv, and must free it at the end of the application using SQLFreeEnv. An environment 
handle is of type HENV. 

e Connections An application can have several connections associated with its environment. Each 
connection must be allocated using SQLAlIlocConnect and freed using SQLFreeConnect. Your 
application can connect to a data source using either SQLConnect, SQLDriverConnect or 
SQLBrowseConnect, and disconnect using SQLDisconnect. A connection handle is of type 
HDBC. 

© Statements Each connection can have several statements, each allocated using SQLAIlocStmt 
and freed using SQLFreeStmt. Statements are used both for cursor operations (fetching data) and 
for single statement execution (e.g. INSERT, UPDATE and DELETE). A statement handle is of 
type HSTMT. 


All access to these objects is through function calls; the application cannot directly access any 
information about the object from its handle. In the Windows and Windows NT environments, all the 
function calls are described in full detail in the ODBC API help file (ODBCAPI.HLP) provided with 
the Windows and Windows NT installations of SQL Anywhere. 
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Cs ~piling and linking an ODBC application 





Every C source file using ODBC functions must include one of the following lines: 


Windows 3.x #include "winodbc.h" 

DOS #include "dosodbc.h" 

32-bit DOS #include "ds32o0dbc.h" 

OS/2 #include "os2odbc.h" 

Windows 95 and NT #include "ntodbc.h" 
QNX #include "qnxodbc.h" 

32-bit QNX #include "qnxodbc.h" 


These files all include the main ODBC include file ODBC.H, which defines all of the functions, data 
types and constant definitions required to write an ODBC program. The file ODBC.H and the 
environment specific include files are installed in the H subdirectory of the SQL Anywhere installation 
directory (usually C:\SQLANY50). 


Once your program has been compiled, you must link with the appropriate library file to have access to 
the ODBC functions: 
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Windows 3.x ODBC.LIB, which defines the entry points into the Driver Manager ODBC.DLL. If 
you connect to a SQL Anywhere database in Windows, ODBC.DLL will load the SQL Anywhere 
ODBC driver, WODS50W.DLL. 
DOS WODBCWCL.LIB, which is a large model WATCOM C library. You will also need the 
SQL Anywhere interface library DBLIBWCL.LIB. 

WODBCMCL.LIB, which is a large model Microsoft C library. You will also need the SQL 
Anywhere interface library DBLIBMCL.LIB. 

WODBCBCL.LIB, which is a large model Borland C library. You will also need the SQL 
Anywhere interface library DBLIBBCL.LIB. 
32-bit DOS WODBCWFG LIB, which is a 32-bit flat model WATCOM C library. You will also 
need the SQL Anywhere interface library DBLIBWFG.LIB. 
OS/2 WODBC2.LIB, which defines the entry points into the SQL Anywhere ODBC driver, 
WODS02.DLL. 
Windows 95 and NT WODBC32.LIB, which defines the entry points into the Driver Manager 
ODBC32.DLL. If you connect to a SQL Anywhere database in Windows NT, ODBC32.DLL wiil 
load the SQL Anywhere ODBC driver, WODSOT.DLL. 
32-bit QNX odbc3r.lib, which is a 32-bit WATCOM C library. You will also need the SQL 
Anywhere interface library dblib3r.hb. 
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The following is a simple ODBC program: 


{ 


Notes 


HENV env; 
HDBC dbec; 
HSTMT stmt; 


SQLAllocEnv( &ampenv ); 
SQLALlocConnect( env, &ampdbc ); 
SOLConnect{ dbc, “sademo", SQL_NTS, 

"dba", SQL_NTS, "sql", SOL_NTS ); 
SQLSetConnectOption( dbc, SQL_AUTOCOMMIT, FALSE ); 
SQLAlLlocStmt( dbc, &ampstmt ); 


/* Delete all the order items for order 2015 */ 
SQLExecDirect( stmt, 
"delete from sales_order_items where id=2015", 
SQL_NTS }; 


/* Use rollback to undo the delete */ 
SQLTransact{ env, dbc, SQL_ROLLBACK )j; 
SOLFreeStmt( stmt, SQL_DROP ); 
SQLDisconnect( dbc ); 

SQLFreeConnect{ dbc }; 

SOQLFreeEnv( env ); 


SQL_NTS Every string passed to ODBC has a corresponding length. If the length is unknown, you 
can pass SQL_NTS indicating that it is a 'Null Terminated String’ whose end is marked by the null 
character (‘\0'). 


SQLExecDirect Executes the SQL statement specified in the parameter. 


SQLTransact Used to perform COMMIT and ROLLBACK statements marking the end of a 
transaction. You should not use SQLExecDirect to perform COMMIT or ROLLBACK. 
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When the Macintosh version of SQL Anywhere becomes available, developers of client applications 
other than PowerBuilder applications should follow the guideline in this section. Failure to do so could 
have severe effects on performance. 


You should define a callback function to be used by the SQL Anywhere ODBC driver when it 
encounters an event it does not know how to handle. This callback function is particularly important if 
an update event gets into the application's queue. If this update event is not explicitly handled, and 
hence remains in the queue, the interprocess communication between the SQL Anywhere ODBC driver 
and the engine or client slows down dramatically, because of the high priority assigned to update 
events by the Macintosh operating system. 


To define the callback function, you should include the provided C language header file EVENTCB.H. 
This header file has the following contents: 


#define WSOQL_OPT_REGISTER_CALLBACK_EVENTS 1900 
typedef void pascal {MAC_EVENT_CALLBACK) ( EventRecord * theEvent }); 
typedef MAC_EVENT_CALLBACK * MAC_EVENT_CALLBACK_PTR; 


You should define the callback function as follows (the name may be changed. 


#include "eventcb.h" 
static void pascal EventHandler( EventRecord * theEvent ) 
{ 
switch( theEvent->what ) { 
// The usual event processing goes here. 
// MUST process updateEvt fully, even if 
// just discarding as shown here. 
case updateEvt: 
BeginUpdate( (WindowPtr) theEvent->message ); 
EndUpdate( (WindowPtr) theEvent->message ); 
break; 


} 


Other events may also be handled; updateEvt must be handled to avoid performance degradation. 


The following fragment illustrates how to use the callback function. 


extern void main{) 
{ 
i. ae 
SOLAllocConnect( env, &ampconnection ); 
// normal connection stuff 
SQLSetConnectOption( connection, 
WSQL_OPT_REGISTER_CALLBACK_EVENTS, 
(UDWORD) EventHandler }; 
Pe hes 
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